Back to Main Menu

Retrieve Functional Locations

Introduction

The Assetic REST Asset API's can be used to retrieve Functional Location detail on a per Functional Location basis or as a paginated list of Functional Locations.  These API's are intended for use in integration processes and not for bulk data extracts, for which the Using Advanced Search to bulk export process is more appropriate.

 

Please read the article Asset Integration Overview if unclear how these endpoints relate to the asset structure in Assetic.

 

There is rate limit applied to the Assetic REST API's which should be considered when attempting to create a large number of records.

API endpoints

There following Assetic REST API endpoints are available for retrieving Functional Location detail:

  • GET /api/v2/functionallocations/{id}
      • Get a functional location using the either the user visible Functional Location ID or the Assetic internal GUID for the functional location.
  • GET /api/v2/functionallocations
      • Retrieve a paginated collection of functional locations based on a search filter

Filtering and sorting

For the Assetic REST API endpoint GET /api/v2/functionallocations the results may be filtered and sorted by the core asset/component fields.

 

For more details refer to Search Filters and Pagination

 

Filltering and ordering by Attribute fields is not supported for attribute fields, only core fields are supported.  To apply a search filter or sort ordering to an attribute field use the Advanced Search API or OData endpoint instead.

Pagination

For the Assetic REST API endpoints with paginated results there is a 500 records per page maximum and a 20 record default. Unlike the Advanced Search API there is no limit to the number of pages that may be returned.

 

The 'pageSize' parameter is used to set page size, and 'page' parameter used to set the page number.

Attributes

The Assetic REST API's GET /api/v2/functionallocation/{id} and GET /api/v2/functionallocation return a small set of core asset fields.  Additional attribute fields may be specified as a list as part of the GET request.  An 'attribute' field is any of the fields that are in the pages contained within the 'Attributes' dropdown list in the Assetic application.

 

To obtain a list of the asset attribute field names to include in the GET request use the Advanced Search Metadata API to get  the 'field name' (not 'label').  To use this API first create and advanced search with the attribute fields that you require field names for.  Save the profile and then use that in the Advanced Search Metadata API

 

Attribute fields are optionally included via the 'attributes' parameter. They can be supplied as a comma separated list.

 
Note: The apidocs page requires at least one attribute to be defined for the endpoints GET /api/v2/assets/{id} and GET /api/v2/assets, but this is not the case if not testing the API's via this page.

Core Functional Location Fields

The core Functional Location fields that are always returned by the Functional Location API's are listed in the article Asset Integration Overview

Sample Payload

The following request retrieves an functional location using the user visible Functional Location ID "ABBFL2".
The 'Zone' attribute is also specified for return by the response

https://xxx.assetic.net/api/v2/functionallocations/ABBFL2?attributes=GroupAssetZone

The following request retrieves an asset using the system GUID for the Functional Location.  In this example there are no additional attributes requested.

https://xxx.assetic.net/api/v2/functionallocations/3c726e2d-ab4f-e611-9465-06edd62954e7

The following request retrieves a paginated list of Functional Locations including the attribute fields 'Zone' and 'Comment':

https://xxx.assetic.net/api/v2/functionallocations?attributes=GroupAssetZone,GroupAssetComment

The default page size is 20, and the first page is returned.